QuickTime For Windows Programmers

Initializing and Terminating QTML and QuickTime

Before your program can perform any QuickTime operations, you must initialize the QuickTime Media Layer and then QuickTime itself. The first is accomplished by calling a routine named InitializeQTML , the second with EnterMovies .

InitializeQTML must be called at the very beginning of your program, before any other QuickTime call. The recommended place to call it is in your WinMain function, before creating your main window. The function is defined as follows:



 
OSErr InitializeQTML (long flag);

The flag parameter allows you to specify certain options for the way QuickTime will behave:

kInitQTMLUseDefault: Use standard behavior.
kInitQTMLUseGDIFlag: Use the Windows Graphics Device Interface (GDI) for all drawing, rather than the DirectDraw or DCI services.
kInitQTMLNoSoundFlag: Don't initialize the Sound Manager; disable sound for all movies.
kInitializeQTMLDisableDirectSound: Disable QTML's use of DirectSound.
kInitializeQTMLUseExclusiveFullScreenModeFlag: Operate exclusively in full screen mode, in versions of QuickTime later than 3.0.

In most cases, you'll just want to set this parameter to kInitQTMLUseDefault , but other options are also available for unusual cases, either singly or in combination.

The function returns an error code indicating success (zero) or failure (nonzero). You can test this result and take appropriate action in case of failure, such as displaying a message box to inform the user that QuickTime is not available. Depending on the nature of your program, you might then choose either to terminate the program or to continue with QuickTime-related features disabled.

If you are writing a routine that does not know from context whether InitializeQTML has already been called, add a call to InitializeQTML at the beginning of the routine and a call to TerminateQTML at the end. It does no harm to call InitializeQTML more than once, as long as each call is nested with a matching call to TerminateQTML. If InitializeQTML has already been called, subsequent calls do nothing except increment a counter. Calls to TerminateQTML just decrement the counter (if it is nonzero). Only the first nested call to InitializeQTML and the last nested call to TerminateQTML do any actual work, so there is no penalty for having nested calls.

The EnterMovies function allocates space for QuickTime's internal data structures and initializes their contents. Your program should call this function immediately after calling InitializeQTML . The function takes no parameters and returns an error code:



 
OSErr  EnterMovies (void);

Again, you can test the result and do whatever is appropriate in case of failure.

At the end of the program, your initialization calls to InitializeQTML and EnterMovies should be balanced by corresponding calls to the termination routines ExitMovies and TerminateQTML . Both of these functions take no parameters and return no result:



 
void  ExitMovies (void)

void  TerminateQTML (void)

Listing 2 shows how these initialization and termination calls fit into the structure of a typical WinMain routine.

Listing 2 Main routine of a Windows program using QuickTime



 
int CALLBACK WinMain (HINSTANCE hInstance, HINSTANCE hPrevInstance,

                      LPSTR lpCmdLine, int nCmdShow)

    {

        MSG     msg;

        HANDLE  hAccelTable;

        

        if  ( !hPrevInstance )                      // Is there a previous instance?

            if ( !(InitApplication(hInstance)) )            // Register window class

                return (FALSE);                             // Report failure

        

        if ( InitializeQTML(0) != noErr )                   // Initialize QTML

            {   

                MessageBox (hWnd, "QuickTime not available", // Notify user

                                "", MB_OK);

                return (FALSE);                             // Report failure

                

            }  /* end if ( InitializeQTML(0) != noErr ) */

        

        if ( EnterMovies() != noErr)                        // Initialize QuickTime

            {   

                MessageBox (hWnd, "QuickTime not available", // Notify user

                                "", MB_OK);

                return (FALSE);                             // Report failure

                

            }  /* end if ( EnterMovies() != noErr ) */

        



        if ( !(InitInstance(hInstance, nCmdShow)) )         // Create main window

            return (FALSE);                                 // Report failure

        

        hAccelTable = LoadAccelerators(hInstance,           // Load accelerator table

                        MAKEINTRESOURCE(IDR_ACCELSIMPLESDI));

        

        

        ///////////////////////////////////////////////////////////////////////////////

        //  Main message loop

        ///////////////////////////////////////////////////////////////////////////////

        

        while ( GetMessage(&msg, NULL, 0, 0) )      // Retrieve next message



            if ( !TranslateAccelerator (msg.hwnd,   // Check for keyboard accelerator

                            hAccelTable, &msg) )

                {

                    TranslateMessage(&msg);         // Convert virtual key to character

                    DispatchMessage(&msg);          // Send message to window procedure

                    

                }  /* end if ( !TranslateAccelerator (msg.hwnd, hAccelTable, &msg) ) */

        

        ///////////////////////////////////////////////////////////////////////////////

        

        

        ExitMovies();                                       // Terminate QuickTime

        TerminateQTML();                                    // Terminate QTML

        

        return (msg.wParam);

        

    }  /* end WinMain */